Tour 1 - Temperature

In this Quick Tour we will recreate the Temperature example. It demonstrates AppMaker's programming model, separating user interface (UI) from data "engine", and connecting UI elements to data elements.

Creating a File
Defining Data
Creating the User Interface
Adding Your Code
Generating Code
Compiling and Linking
Running the Built Application

Creating a File

If you just finished the Registration dialog, then choose New from the File menu. If you had previously entered your registration information, you will see an Open file dialog. Click New. In either case, AppMaker displays an Untitled window.
Choose Save or Save As. In the standard file dialog, first create a new folder named Tour1, then name the file as Temperature.

Defining Data

In the Temperature window, twist DataDefs, then select DocData.
(Is "twist" a standard term? We use it to mean click the disclosure triangle to the left of DataDefs so that the triangle points down and displays the contents of DataDefs, in this case a single DataDef named DocData.)
Choose Open Properties from the View menu. AppMaker displays a window showing the Members of DocData (currently none).
Choose Create Member from the Edit menu. AppMaker displays a dialog for entering information about the data member.
Type Centigrade as the title. For the Kind, choose Integer, then using the small popup to the right of Type, choose SInt16. Then click OK.
Press Command-K as the shortcut for Create Member. Type Fahrenheit as the title, and again choose Integer as the Kind and SInt16 as the type. Click OK.
Close the DocData window.

Creating the User Interface

Run the pre-built Temperature68K example (it's in the AppMaker 2: Examples folder) as a guide for creating the main window.

In the Temperature window, twist Windows, then double-click MainWindow.
From the View menu, choose Tools, then select the Static Text tool.
In MainWindow, click near the upper left corner, then type Centigrade:
Select the Edit Text tool.
Click below the Centigrade label to create an edit field.
Choose Edit Text Info from the View menu. AppMaker opens a dialog box to let you specify information about the edit field.
Type CentEdit as the title, then choose integer as the Flavor.
Click the Target Data button. In the Choose Path dialog, double-click DocData, then double-click Centigrade. This connects the Centigrade edit field to the Centigrade data member.
Click OK to close the Info dialog.
Resize the CentEdit item to hold about three digits.
From the Tools palette, choose the Scrollbar tool.
Click below the CentEdit field. In the ScrollBar Info dialog, type CentSlider as the title.
Click the Target Data button. In the Choose Path dialog, double-click DocData, then double-click Centigrade. Both the edit field and this scrollbar are now connected to the Centigrade data member.
Type a Min of -20 and a Max of 40, then choose Slider as the Flavor. (If you will be running on System 7 without the Appearance extension, then instead choose Jim's Slider. We strongly recommend using the Appearance extension. It makes all the new Mac OS 8 controls available under System 7.)
Click OK to finish creating the slider.
In a similar fashion, create Fahrenheit items to the right of the Centigrade items. Create a Fahrenheit: label. Create a Fahrenheit edit field titled FahrEdit. For its TargetData choose the Fahrenheit data member. Remember to choose integer as the flavor.
Next, create a thermometer. Choose the Progress Bar tool from the tools palette, then click below the FahrEdit field.
In the Progress Bar Info dialog, type FahrBar as the title. For TargetData again choose the Fahrenheit data member. Now both the edit field and the progress bar are connected to the same data.
Type Min of 0 and Max of 100, then choose Round Rect as the flavor.
Click OK, then resize the thermometer to the same size as the Centigrade Slider item.
Close the MainWindow. (For the pre-built Temperature we resized MainWindow, set its drawing style to a gray background, and removed its grow box and zoom box. We have omitted those steps from this Quick Tour to save time.)

Adding Your Code

When creating the user interface, we connected the CentEdit field and the CentSlider to the Centigrade data member. Changing either UI item will automatically change the data member and will change the other UI item. I.e. typing a value into the edit field will change the slider, and changing the slider will change the value of the edit field. Similarly, the FahrEdit field and the FahrBar are connected to the Fahrenheit data member. Typing into the edit field will change the thermometer.

What's missing is a connection between the Centigrade items and the Fahrenheit items. In this section we will add code to convert between Centigrade and Fahrenheit and to change all of the UI items whenever any one of them is changed.

In the Temperature window, twist open DataDefs if not already open. Twist DocData to show its two members, Centigrade and Fahrenheit.
Double-click Centigrade to display the Member Info dialog.
For Initial value type 10.
For the "Set" code type: (Your browser may let you Copy this code.) mFahrenheit = ((18 * mCentigrade) + 5) / 10 + 32; SignalDataChanged (idFahrenheit); AppMaker will later insert this code fragment into the generated code. This code is in the C language. If you are using another language, you may have to alter this code slightly.
Click OK to finish setting the Centigrade Info.
Similarly, double-click the Fahrenheit member to set its info.
For Initial value type 50.
For the "Set" code type: mCentigrade = ((10 * (mFahrenheit - 32)) + 9) / 18; SignalDataChanged (idCentigrade);
Click OK to finish setting the Fahrenheit Info.

Here is the contest we announced earlier. The two formulas above have a very small bug. To the first reader who offers a simple correction we will extend your AppMaker subscription. To enter the contest, just send e-mail to BowersDev@aol.com.

These few lines of code cause both the Centigrade value and the Fahrenheit value to be changed whenever either one is changed. When a UI item changes the Centigrade value, then the UI items connected to the Fahrenheit data member will also change. Similarly, changing a Fahrenheit UI item will change the two Centigrade UI items.

Generating Code

In the Temperature window, twist Applications then double-click YourApp.
In the Application Info dialog, type Temperature as the title, then click OK.
Twist Documents then double-click YourApp.
In the Document Info dialog, type Temperature as the title, then click OK.
Choose Save from the File menu to save your changes.
Choose Generate from the File menu, then choose C/C++ OS8 as the language.
When AppMaker is finished generating code, click Done then choose Quit.

Compiling and Linking

In the Finder, open your AppMaker folder. In that folder is a Projects folder. Open "Projects: CodeWarrior Pro 4 (or Pro 3, Pro 2): C/C++ OS8".
In that folder are two items, YourApp and AMToolbox.rsrc. Copy these two files into the Tour1 folder you created at the beginning of this Quick Tour. (If you are running a Demo version of AppMaker then you weren't able to save your file into Tour1 or to generate code into that folder. You might skip the remainder of this Quick Tour and just examine the pre-built example, Examples: C/C++ OS8: Temperature.)
Still in the Finder, Close the Projects, CodeWarrior Pro 3, and C/C++ OS8 windows. Open your Tour1 window. Rename YourApp.u to Temperature.u. Then double-click it to launch CodeWarrior Pro.
NOTE:We set up this project assuming that CodeWarrior's MacOS Support folder contains the Appearance SDK. See the Getting Started chapter for information about how to install Appearance.
In CodeWarrior, click the Settings icon, then choose Target Settings and change the Target Name, then choose PPC Target (or 68K Target) and change the File Name. The project has targets for both 68K and PPC so change the settings for both targets.
In the project window, select the Sources group, then choose Add Files from the Project menu. Click Add All, then click Done. In the following dialog, click OK to add all the generated files to both 68K and PPC targets. (You might remove the ".h" files as unnecessary clutter.)
Click the Make icon to compile and link your Temperature application. Click the Run icon to try it out. Alternatively, in the Finder you can double-click the built application.

Running the Built Application

Type values into either the Centigrade or Fahrenheit fields, then press Enter or the Tab key. Drag the Centigrade slider's indicator. Changing any of the UI items causes all four items to display the new value.

Temperature is a working and useful application that was generated by AppMaker with only four lines of hand-written code.

As a general rule, your code will be part of the "engine" rather than part of the UI. Your code will respond to changes in a data element by computing other data and then signaling that the data has changed. UI code responds to changes in data by displaying new data.

The purpose of a UI is to display data and to modify data. AppMaker generates code that gets data values and displays them in UI elements, then responds to user changes by modifying data elements accordingly. Multiple UI elements, possibly in multiple windows or dialogs, can change the same data element. The generated code listens for changes to the data, then UI elements Get the new data values and display them.

Continue to Tour 2